home *** CD-ROM | disk | FTP | other *** search
/ Aminet 31 / Aminet 31 (1999)(Schatztruhe)[!][Jun 1999].iso / Aminet / dev / gui / gtlayout.lha / Source / gtlayout_lib.c < prev    next >
C/C++ Source or Header  |  1998-09-09  |  22KB  |  710 lines
  1. /*
  2. **    GadTools layout toolkit
  3. **
  4. **    Copyright © 1993-1998 by Olaf `Olsen' Barthel
  5. **        Freely distributable.
  6. **
  7. **    :ts=4
  8. */
  9.  
  10. #ifndef _GTLAYOUT_GLOBAL_H
  11. #include "gtlayout_global.h"
  12. #endif
  13.  
  14. /*****************************************************************************/
  15.  
  16. #include <exec/execbase.h>
  17. #include <exec/resident.h>
  18.  
  19. #include <dos/dos.h>    /* For BPTR definition */
  20.  
  21. /*****************************************************************************/
  22.  
  23. #include "Assert.h"
  24.  
  25. #include "gtlayout.library_rev.h"
  26.  
  27. /*****************************************************************************/
  28.  
  29. /****** gtlayout.library/--version-- ******************************************
  30. *
  31. *   NOTES
  32. *    This document describes gtlayout.library v5.12 or higher. Do not assume that
  33. *    previous library releases support the same features.
  34. *
  35. ******************************************************************************
  36. *
  37. */
  38.  
  39. /****** gtlayout.library/--background-- ******************************************
  40. *
  41. *   NOTES
  42. *    1. General information
  43. *
  44. *    1.1 Purpose
  45. *
  46. *    The GUI code included in this archive helps to create user interfaces
  47. *    using gadtools.library with a minimum of effort. The code
  48. *    automatically takes care of the font to be used, making the user
  49. *    interface font independent. Localizing support is built right into
  50. *    the code, just install a callback hook and pass numeric IDs for the
  51. *    gadget labels: the code will invoke your hook in order to get the
  52. *    text required. Keystroke activation of gadgets is also taken care
  53. *    of, in fact the code will -- unless told not to do so -- assign keyboard
  54. *    shortcuts to the gadgets created all on its own. Every effort has been
  55. *    made to make the code reentrant, so it can be put into a shared library.
  56. *    If a user interface does not fit onto a screen provisions are made to
  57. *    choose a smaller font and to rescale the window contents until they fit.
  58. *    Last but not least the user interface code offers transparent extensions
  59. *    to the standard gadtools.library objects, such as LISTVIEW_KIND objects
  60. *    which respond to double-clicks or STRING_KIND objects which can be used
  61. *    to enter password text as they will not display the characters entered.
  62. *
  63. *
  64. *    1.2 Distribution
  65. *
  66. *    The code is *free*, you don't need to pay any money to use it, nor
  67. *    do you need to quote my name in the documentation, the program or
  68. *    anywhere else. You are allowed to make changes to the code, but if
  69. *    you stumble across any bugs or even know how to fix them, please
  70. *    let me know. It does not matter whether you intend to sell a program
  71. *    to use the code, use the code in shareware, gift-ware, freeware or
  72. *    etc.-ware programs: the code still remains royalty-free.
  73. *
  74. *
  75. *    1.3 Caveats
  76. *
  77. *    The code is pretty large, about 80K-100K bytes in size. Not all
  78. *    gadtools.library type objects are supported, notably
  79. *    GENERIC_KIND objects. The code is not as flexible as
  80. *    gadtools.library, so certain things which are easily done using
  81. *    gadtools.library may be pretty difficult or even impossible.
  82. *    The code is written entirely in `C' and requires SAS/C to
  83. *    compile. Some parts of the code are highly recursive; I haven't
  84. *    tested how much stack they might require in certain cases,
  85. *    but I recommend that you don't overuse the grouping feature.
  86. *    The data structures required to create and maintain the
  87. *    user interface are huge, a single window might require more
  88. *    than 4K-6K of memory. Proportional font support only works
  89. *    well starting with Kickstart v39 and up, v2.04 will probably
  90. *    not look quite that pretty.
  91. *
  92. *
  93. *    2. Programming
  94. *
  95. *    2.1 Client libraries required for link library version
  96. *
  97. *    You need to have SysBase and GadToolsBase initialized in order to make
  98. *    use of the code, i.e. your code has to do
  99. *    WaitPort()...GT_GetIMsg()...GT_ReplyIMsg all on its own. The code makes
  100. *    use of the memory pools introduced in exec.library v39, but calls the
  101. *    equivalent routines in amiga.lib. Note: as of this writing the pools
  102. *    code in amiga.lib v40.14 is broken, so you need to link with Mike
  103. *    Sinz' fixed pools.lib.
  104. *
  105. *
  106. *    2.2 Invocation procedure
  107. *
  108. *    The typical invocation procedure looks roughly like this:
  109. *
  110. *       LT_Init();    // only for link library version
  111. *       :
  112. *       :
  113. *          LT_CreateHandleTags();
  114. *             LT_New();
  115. *             :
  116. *             :
  117. *             LT_New();
  118. *                LT_Build();
  119. *                   LT_HandleInput();
  120. *          LT_DeleteHandle();
  121. *       :
  122. *       :
  123. *       LT_Exit();    // only for link library version
  124. *
  125. *    You need to call LT_Init() only once in your program, it will initialize
  126. *    the libraries and global data structures required by the user interface
  127. *    code. When you are finished with the user interface and your program is
  128. *    about to exit you need to call LT_Exit() or memory will get lost.
  129. *    Note that LT_Init() is not protected against multiple invocations. If
  130. *    called repeatedly memory will get lost which can never be reclaimed.
  131. *    However, LT_Exit() is protected against multiple invocations, you can
  132. *    also call it before ever giving LT_Init() a call, but I doubt this
  133. *    would make much sense. If you are using the shared gtlayout.library
  134. *    no call to LT_Init()/LT_Exit() is necessary as these calls are already
  135. *    wrapped into the library opening code.
  136. *       Before you can actually start building a window layout a call to
  137. *    LT_CreateHandleTags() needs to be made. You need to pass in a pointer
  138. *    to the Screen your user interface window is to be opened on and,
  139. *    optionally, a few tags to control the look and performance of the
  140. *    interface. *Never* close the screen in question before calling
  141. *    LT_DeleteHandle() or nasty things will happen. For public screens
  142. *    the code will try to lock the screen in question. With the handle
  143. *    LT_CreateHandleTags() returned you can call LT_New() to build the
  144. *    user interface. When finished a call to LT_Build() will finally
  145. *    open a window and place the gadgets inside. A pointer to the
  146. *    Window created will be returned, ready to be used for the
  147. *    WaitPort()...GT_GetIMsg()...LT_HandleInput()...GT_ReplyIMsg()
  148. *    loop. When finished, a call to LT_DeleteHandle() will close the
  149. *    window and release all the memory associated with it. The design
  150. *    of the interface code is similar to the corresponding calls in
  151. *    gadtools.library, i.e. you don't need to worry about LT_New()
  152. *    failing to allocate memory for the objects required. When it comes
  153. *    to LT_Build() the code will know about any trouble which would
  154. *    show up during previous invocations of LT_New(). In essence,
  155. *    if LT_Build() returns NULL something is wrong.
  156. *
  157. *
  158. *    2.3 Hierarchic grouping
  159. *
  160. *    The basic building block of the user interface is a group, either
  161. *    a horizontal or a vertical group. Adding gadgets or other objects
  162. *    to a horizontal group will place them side by side from left to
  163. *    right. A vertical group causes objects to be place from top to
  164. *    bottom in one straight line. Groups help to arrange objects
  165. *    neatly stacked, centered and properly aligned with other
  166. *    members of the group.
  167. *
  168. *    MUCHO IMPORTANTE: there is a bug lurking in the code which I never
  169. *    had the luck to find and fix. One would expect to create
  170. *    user interface structures like this:
  171. *
  172. *       <group start>
  173. *          <button>
  174. *          <list>
  175. *          <group start>
  176. *             <slider>
  177. *             <text>
  178. *          <group end>
  179. *          <button>
  180. *       <group end>
  181. *
  182. *    However, it is in fact not possible to mix gadgets and groups.
  183. *    Thus, the user interface structure would have to look like this:
  184. *
  185. *       <group start>
  186. *          <group start>
  187. *             <button>
  188. *             <list>
  189. *          <group end>
  190. *          <group start>
  191. *             <slider>
  192. *             <text>
  193. *          <group end>
  194. *          <group start>
  195. *             <button>
  196. *          <group end>
  197. *       <group end>
  198. *
  199. *    Or in other words: groups only mix with other groups.
  200. *
  201. *    You build groups using three different object types. In this
  202. *    context `object type' refers to a specific numeric value the
  203. *    LT_New() routine knows which will cause it to add another leaf
  204. *    to the user interface structure tree. Here is an example:
  205. *
  206. *       struct LayoutHandle *Handle;
  207. *
  208. *       if(Handle = LT_CreateHandleTags(NULL,
  209. *          LAHN_AutoActivate,FALSE,
  210. *       TAG_DONE))
  211. *       {
  212. *          struct Window *Window;
  213. *
  214. *          LT_New(Handle,
  215. *